home *** CD-ROM | disk | FTP | other *** search
/ Aminet 45 / Aminet 45 (2001)(GTI - Schatztruhe)[!][Oct 2001].iso / Aminet / game / role / ldmud-3.2-bin.lha / mud / doc / efun / input_to < prev    next >
Text File  |  2001-04-03  |  4KB  |  96 lines
  1. SYNOPSIS
  2.         #include <input_to.h>
  3.  
  4.         void input_to(string|closure fun)
  5.         void input_to(string|closure fun, int flag, ...)
  6.  
  7. DESCRIPTION
  8.         Enable next line of user input to be sent to the function <fun>
  9.         as an argument. Exception: if the next input
  10.         line starts with a "!", it will be parsed as a command resp.
  11.         passed to the most recent input_to() given with the
  12.         INPUT_IGNORE_BANG flag.
  13.         The function <fun> may be static, but must not be private (or
  14.         it won't be found).
  15.  
  16.         Note that fun is not called immediately but after pressing the
  17.         RETURN key.
  18.  
  19.         If input_to() is called more than once in the same execution,
  20.         only the first call has any effect. On the other hand, if
  21.         a command given during an input_to() (using the "!" escape)
  22.         issues its own input_to(), the previous input_to() is suspended
  23.         until the new input_to() has been handled, then the previous
  24.         one becomes active again.
  25.  
  26.         The optional argument <flag> may be a binary-OR ('|') of the
  27.         following option values:
  28.  
  29.           INPUT_NOECHO  (1):
  30.               The line given by the player will not be echoed, and is
  31.               not seen if snooped.
  32.  
  33.           INPUT_CHARMODE  (2):
  34.               The connection is switched from line- into charmode to
  35.               retrieve a single character(!) from the player.
  36.               
  37.               After execution of <fun>, the connection is switched
  38.               back into linemode unless a subsequent input_to( , 2)
  39.               has been issued.
  40.  
  41.               Lineends are received depending on how the client sends
  42.               them: either as "", as "\r" followed by "", or (happens
  43.               with Windows clients) as just "\r".
  44.  
  45.               Note that the players frontend is free to stay in
  46.               linemode all the time: even if you request a single
  47.               character, the player might be forced to type (and send)
  48.               that character plus the return key. Usually your function
  49.               will then receive the complete input in one call.
  50.  
  51.               If you plan to stay in charmode a longer time , you can
  52.               reduce the call overhead by using set_combine_charset()
  53.               to retrieve sequences of certain characters as one string
  54.               instead of one-by-one. In a screen-oriented editor for
  55.               example this would be most of the printable characters.
  56.  
  57.           INPUT_IGNORE_BANG  (128):
  58.               Input lines starting with '!' will _not_ be parsed as
  59.               commands, but are given to the function as well. Usage
  60.               of this option is privileged.
  61.  
  62.         The optional 3rd and following args will be passed as second and
  63.         subsequent args to the function fun.
  64.  
  65. EXAMPLE
  66.         void func() {
  67.            ...
  68.            write("Please enter your name:");
  69.            input_to("enter_name");
  70.            ...
  71.         }
  72.         enter_name(string str) {
  73.            write("Is '"+str+"' really your name?? *giggle*\n");
  74.            ...
  75.         }
  76.  
  77.         When reaching the input_to() statement the driver
  78.         continues the function func() but also asks the user for
  79.         input. If you entered whatever is asked and press RETURN the
  80.         driver will invoke the enter_name() function with the
  81.         string you entered as argument to it.
  82.  
  83. HISTORY
  84.         The meaning of the flag parameter was extended in 3.2.1@93.
  85.         The limited "stacking" of input_to()s issued from !-commands
  86.         was implemented in LDMud 3.2.8.
  87.         Since LDMud 3.2.8 the function can be given as a closure.
  88.  
  89. BUGS
  90.         In CHARMODE, newlines should really be returned as "\n"; however,
  91.         this might break existing code.
  92.  
  93. SEE ALSO
  94.         call_other(E), sscanf(E), privilege_violation(M),
  95.         set_combine_charset(E)
  96.